feat(multiagent): Add stream_async #961

mkmeral · 2025-10-02T11:13:12Z

Description

This PR adds streaming support to the Swarm and Graph multi-agent systems, enabling real-time event emission during multi-agent execution. This brings multi-agent systems to feature parity with the single Agent class streaming capabilities.

Key Changes

New Event Types (src/strands/types/_events.py):

MultiAgentNodeStartEvent: Emitted when a node begins execution
MultiAgentNodeCompleteEvent: Emitted when a node completes execution
MultiAgentNodeStreamEvent: Forwards agent events with node context
MultiAgentHandoffEvent: Emitted during agent handoffs in Swarm (includes from_node, to_node, and message)

Swarm Streaming (src/strands/multiagent/swarm.py):

Added stream_async() method that yields events during execution
Refactored invoke_async() to use stream_async() internally (maintains backward compatibility)
Events include node start/complete, forwarded agent events, handoff notifications, and final result
Proper event emission even during failures

Graph Streaming (src/strands/multiagent/graph.py):

Added stream_async() method for real-time event streaming
Refactored invoke_async() to consume stream_async() events
Supports streaming from parallel node execution
Events maintain node context throughout execution

Testing:

Comprehensive test coverage for streaming functionality in both Swarm and Graph
Tests for parallel execution, handoffs, failures, and timeouts
Backward compatibility tests to ensure existing code continues to work

Benefits

Real-time visibility into multi-agent execution progress
Consistent streaming API across single and multi-agent systems
Better debugging and monitoring capabilities
Foundation for UI progress indicators and live updates

Related Issues

Documentation PR

Type of Change

New feature

Testing

How have you tested the change?

Added comprehensive unit tests for streaming in both Swarm and Graph (tests/strands/multiagent/test_swarm.py, tests/strands/multiagent/test_graph.py)
Tests cover: basic streaming, parallel execution, handoffs, failures, timeouts, and backward compatibility
All existing tests pass, confirming backward compatibility

Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

I ran hatch run prepare

Checklist

I have read the CONTRIBUTING document
I have added any necessary tests that prove my fix is effective or my feature works
I have updated the documentation accordingly
I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
My changes generate no new warnings
Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

src/strands/multiagent/swarm.py

zastrowm · 2025-10-06T17:40:41Z

src/strands/multiagent/graph.py

+
+        Yields:
+            Dictionary events containing graph execution information including:
+            - MultiAgentNodeStartEvent: When a node begins execution


These types aren't exposed to customers, so we should either remove these docs or document the shape of the dictionaries being emited

Can you also list out the the new events to the PR description (similar to #788) along with the signatures of the new apis being added. This well help the PR be more akin to the spec of what's being proposed

so we should either remove these docs AND document the shape of the dictionaries being emitted*

I have matched the implementation/documentation to agent. I will add additional docs as a followup CR on docs repo. I will also update the RP description to explain the events emitted.

zastrowm · 2025-10-06T17:43:40Z

src/strands/multiagent/graph.py

+            try:
+                event = await asyncio.wait_for(async_generator.__anext__(), timeout=timeout)
+                yield event
+            except StopAsyncIteration:


Is this always thrown at the end and thus part of normal execution?

nit: seems like theres might be a more pythonic way to do this without the while

async with asyncio.timeout(timeout): async for event in async_generator:

zastrowm · 2025-10-06T17:46:39Z

src/strands/multiagent/graph.py

-            # because a failure would throw exception and code would not make it here
            ready_nodes.extend(self._find_newly_ready_nodes(current_batch))

+    async def _execute_nodes_parallel(


Does this follow the pattern of how tools are executed in parallel - I know we worked out some wrinkles/bugs with that, so it'd be ideal to not have to redo those

Also, does this have to be in this PR? Can we do the streaming then add parallel execution as a different commit to simplify the review?

Parallel calls should be in this PR as graph already supports them.

w.r.t. bugs, I have updated the logic similar to #954 . is there anything else?

zastrowm · 2025-10-06T17:47:52Z

src/strands/multiagent/graph.py

+        start_event = MultiAgentNodeStartEvent(
+            node_id=node.node_id, node_type="agent" if isinstance(node.executor, Agent) else "multiagent"
+        )
+        yield start_event.as_dict()


Could we do this at a higher level instead of in here? That way we can ensure this method is always returning TypedEvents

Same for below

zastrowm · 2025-10-06T17:48:43Z

src/strands/multiagent/graph.py

+                            wrapped_event = MultiAgentNodeStreamEvent(node.node_id, event)
+                            yield wrapped_event.as_dict()
+                            # Capture the final result event
+                            if "result" in event:


Can we just do an isinstance check here?

Not easily, because agent also translates it to a dict before returning the responses. https://github.com/strands-agents/sdk-python/blob/main/src/strands/agent/agent.py#L591

Is there a reason we decided to go this way instead of returning typed events?

src/strands/multiagent/graph.py

src/strands/multiagent/swarm.py

zastrowm · 2025-10-06T17:54:30Z

src/strands/multiagent/swarm.py

-
-                except Exception:
-                    logger.exception("node=<%s> | node execution failed", current_node.node_id)
+                except Exception as e:


Why can't we use an exception type for this? This seems hacky

dbschmigelski · 2025-10-06T18:17:00Z

src/strands/multiagent/graph.py

            status=Status.EXECUTING,
            task=task,
            total_nodes=len(self.nodes),
            edges=[(edge.from_node, edge.to_node) for edge in self.edges],


note related to this PR, but why doesn't GraphState take Iterable[GraphEdge] instead of edges: list[Tuple["GraphNode", "GraphNode"]] = field(default_factory=list)

Did GraphEdge come later?

dbschmigelski · 2025-10-06T18:28:40Z

src/strands/multiagent/graph.py

+            try:
+                event = await asyncio.wait_for(async_generator.__anext__(), timeout=timeout)
+                yield event
+            except StopAsyncIteration:


nit: seems like theres might be a more pythonic way to do this without the while

async with asyncio.timeout(timeout): async for event in async_generator:

dbschmigelski · 2025-10-06T18:29:51Z

src/strands/multiagent/graph.py

-            # because a failure would throw exception and code would not make it here
            ready_nodes.extend(self._find_newly_ready_nodes(current_batch))

+    async def _execute_nodes_parallel(


Also, does this have to be in this PR? Can we do the streaming then add parallel execution as a different commit to simplify the review?

dbschmigelski · 2025-10-06T18:30:40Z

src/strands/multiagent/swarm.py

+        self, async_generator: AsyncIterator[dict[str, Any]], timeout: float, timeout_message: str
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Wrap an async generator with timeout functionality."""
+        while True:


same nit as in graph

dbschmigelski · 2025-10-06T18:35:51Z

src/strands/multiagent/swarm.py

-                    logger.exception("node=<%s> | node execution failed", current_node.node_id)
+                except Exception as e:
+                    # Check if this is a timeout exception
+                    if "timed out after" in str(e):


nit: can we create a variable for this so we don't accidentally change the message in exception

- Update docstrings to match Agent's minimal style (use dict keys instead of class names) - Add isinstance checks for result event detection for type safety - Improve _stream_with_timeout to handle None timeout case - Add MultiAgentResultEvent for consistency with Agent pattern - Yield TypedEvent objects internally, convert to dict at API boundary - All 154 tests passing

- Remove unnecessary asyncio.gather() after event loop completion - Same issue as tool executor PR strands-agents#954 - By the time loop exits, all tasks have already completed - Gather was waiting for already-finished tasks (no-op) - All 154 tests passing

codecov · 2025-10-10T11:29:12Z

Codecov Report

❌ Patch coverage is 90.32258% with 15 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/strands/multiagent/graph.py	91.95%	2 Missing and 5 partials ⚠️
src/strands/multiagent/swarm.py	87.75%	4 Missing and 2 partials ⚠️
src/strands/multiagent/base.py	50.00%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

Murat Kaan Meral added 3 commits October 2, 2025 12:45

feat(multiagent): Add stream async

6c00bbe

Merge branch 'main' into multiagent-streaming

b09b539

fix(graph): improve parallel node calling

08141a0

mkmeral had a problem deploying to auto-approve October 2, 2025 11:13 — with GitHub Actions Failure

fix: Fix double execution

d4f5571

mkmeral had a problem deploying to auto-approve October 2, 2025 13:00 — with GitHub Actions Failure

mkmeral marked this pull request as draft October 2, 2025 13:07

fix: improve graph timeout

fc0a272

mkmeral had a problem deploying to auto-approve October 3, 2025 09:59 — with GitHub Actions Failure

Murat Kaan Meral added 2 commits October 3, 2025 12:20

Merge branch 'main' into multiagent-streaming

ca59221

fix: Add integ tests

60f16b9

mkmeral had a problem deploying to auto-approve October 3, 2025 10:28 — with GitHub Actions Failure

mkmeral marked this pull request as ready for review October 3, 2025 10:32

zastrowm requested changes Oct 6, 2025

View reviewed changes

dbschmigelski reviewed Oct 6, 2025

View reviewed changes

Murat Kaan Meral added 2 commits October 10, 2025 13:07

mkmeral had a problem deploying to auto-approve October 10, 2025 11:27 — with GitHub Actions Failure

feat(multiagent): Add stream_async #961

Are you sure you want to change the base?

feat(multiagent): Add stream_async #961

Conversation

mkmeral commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Key Changes

Benefits

Related Issues

Documentation PR

Type of Change

Testing

Checklist

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Oct 10, 2025

Codecov Report

Uh oh!

Uh oh!

mkmeral commented Oct 2, 2025 •

edited

Loading